The help output names the three documents an operator is owed - #173

Part of #36.

An operator who runs the binary and never opens the repository had no route to
the intended-use notice, the licence or the privacy document. The runner knew
where all three were and said nothing about any of them, so for that reader the
three files did not exist.

The last paragraph of the usage text now names them. It names rather than
restates, because a paraphrase printed by a binary somebody downloaded months
ago is a copy of a document that has since moved on, and the reader has no way
to tell which of the two they are holding.

go run ./cmd/lab help
lab reads this repository and reports what it examined.

    lab check [path]   walk the tree at path, default ".", and report
    lab list [path]    list the experiments at path, default ".", oldest
                       unanswered first
    lab help           print this text

lab writes nothing to the tree it reads.

NOTICE.md says what this program is for, LICENSE carries the terms it is under,
and docs/privacy.md says what stays on the host. Reading them is on you; this
text only says where they are.
exit=0

The two limits #36 asks for at the code are at the declaration rather than only
in the issue. A notice is not a control and printing it prevents nothing, so it
should not be counted as a thing that stops misuse when somebody later asks what
does. And a notice an operator has to run a verb to see is weaker than one
sitting in the download beside the binary, which is why both routes are wanted
rather than either alone.

What this does not close

Neither clause of the done-condition on #36.

The first asks that lab --help and the version output both name the three
files. The runner takes verbs and no flags, so that spelling reaches the
unknown-verb branch and returns the code record 0011 gives a broken
invocation, and there is no version output of any kind:

go run ./cmd/lab --help
lab: unknown verb "--help"
...
exit status 2

go run ./cmd/lab version
lab: unknown verb "version"
exit status 2

The second asks that the release archive carry the three files next to the
binary, and there is nothing published for them to sit beside:

gh api repos/Flowfin/lab/releases --jq "length"
0

Whether the runner should grow a flag or the done-condition should name
lab help is a question about the command interface, and this change does not
take it. The paragraph landing here is reached through the spelling that works
today, whichever way that goes.

The guard and the proof it bites

Nothing else in the tree holds these strings. The paths leg of the invariants
scan takes this repository's own documents as its subject, which is the files at
the root and everything under docs/, and isOwnDocument puts a path named
inside the runner outside that subject. A document deleted or moved under this
paragraph would therefore redden nothing, and the binary would go on telling
operators to read a file that is not there.

TestHelpNamesTheDocumentsAnOperatorIsOwed asserts both halves of the walk an
operator makes: that the text names the file, and that the file is in the tree
to be found. Each half was proved by breaking it and watching the suite go red,
then restored.

Deleting the paragraph from the usage text:

go test ./cmd/lab -run TestHelpNamesTheDocumentsAnOperatorIsOwed -count=1
--- FAIL: TestHelpNamesTheDocumentsAnOperatorIsOwed (0.00s)
    main_test.go:243: the help output does not name NOTICE.md:
    main_test.go:243: the help output does not name LICENSE:
    main_test.go:243: the help output does not name docs/privacy.md:
FAIL

Moving one of the named documents out of the tree. The tail of that line is the
operating system's own message, quoted as it arrived:

go test ./cmd/lab -run TestHelpNamesTheDocumentsAnOperatorIsOwed -count=1
--- FAIL: TestHelpNamesTheDocumentsAnOperatorIsOwed (0.00s)
    main_test.go:246: the help output names docs/privacy.md and it is not in this tree: GetFileAttributesEx ..\..\docs\privacy.md: Das System kann die angegebene Datei nicht finden.
FAIL

Both restored, and the tree is green:

go vet ./...
(no output, exit 0)

go test ./... -count=1
ok  	github.com/Flowfin/lab/cmd/contexts	0.431s
ok  	github.com/Flowfin/lab/cmd/lab	7.842s
ok  	github.com/Flowfin/lab/cmd/notices	22.860s
ok  	github.com/Flowfin/lab/cmd/pullrequest	1.176s
?   	github.com/Flowfin/lab/experiments/reading-a-tree-of-records	[no test files]
ok  	github.com/Flowfin/lab/internal/check	2.222s
ok  	github.com/Flowfin/lab/internal/contexts	1.042s
ok  	github.com/Flowfin/lab/internal/hardware	1.172s
ok  	github.com/Flowfin/lab/internal/invariants	1.478s
ok  	github.com/Flowfin/lab/internal/notices	0.928s
ok  	github.com/Flowfin/lab/internal/prose	1.216s
ok  	github.com/Flowfin/lab/internal/pullrequest	1.173s

go run ./cmd/lab check .
examined .
1 experiment directory walked, 1 record read
18 decision records read
the time this run read is 2026-08-23T02:20:46Z
0 refused

The means

Go, which is what the runner is written in and what decision record 0001
fixes. The change is one paragraph of output text, one declaration and one test,
in packages that already exist. It adds no language, no runtime and no
dependency, and it is judged by the suite that is already here rather than
needing an apparatus of its own.

How this landing was rebuilt

An earlier landing of this change carried the same two files and no DCO
sign-off, and the sign-off gate refused it by name:

FAIL  31a68c0b193cdb20080baa7debc0fce3d6e4c3dc is missing: Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>

I did not rewrite that branch. The commit was rebuilt on a fresh branch with the
sign-off, and the two are proven to carry identical content rather than assumed
to:

git show 31a68c0 | git patch-id --stable
2962ce886cd65390d358ec734f0b35ea51013281 31a68c0b193cdb20080baa7debc0fce3d6e4c3dc

git show HEAD | git patch-id --stable
2962ce886cd65390d358ec734f0b35ea51013281 7595a9d4d0d390b5bea8a841201c004edc931c54

The superseded pull request is closed with the reason in its body, and its
branch is left alone.

This body also replaces a first version of itself. The file it was composed into
was read back from a stale path that held unrelated text, and what that produced
was posted here for a few minutes before I read it back and replaced it. The
text above is the body this change was written with.

Reading

This change has had no second reader. The evidence above stands in place of one:
every command is quoted with the output it produced, both directions of the
guard were executed rather than argued, and what the change does not close is
written out here rather than left for a reader to derive from the diff.